<!doctype html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>Upgrading from legacy Theos &middot; Theos</title>
	<meta name="viewport" content="initial-scale=1">
	<meta name="theme-color" content="#382b42">
	<link rel="stylesheet" type="text/css" href="assets/style-a3b52a608a1ac2b7ca829f2867add47324e7484c8280c2df12c5fc1d361022e1.css">
	<link rel="icon" href="assets/favicon-447ec328b50bd5d64f09e1f06fe07532f924f274bd5de6567a43690bf494c99a.svg" sizes="any" type="image/svg+xml">

</head>

<body>
	<header>
	<div class="container">
		<h1>
			<a href="#">
				<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 781 224">
					<title>Theos</title>
					<path d="M155.2 18.4H2.6v36.3H54V218h47.4V54.7h49.2l4.6-36.3zM263 60.2c-18 0-31.7 7.2-44 21V-.3l-45.6 4.6V218H219V113.2c8-12.4 16.3-19.6 26.4-19.6 8.6 0 14.4 4.3 14.4 20.4v104h45.5V106.3c0-29-16-46-42.4-46zm210 78.3c0 5-.4 11.8-1 16.4h-94.4c2.8 27 15.8 34.2 34.5 34.2 13 0 24-4.3 37-13.6l19 25.4c-15.2 12-35 21.4-59.6 21.4-51 0-77-33-77-80.7 0-45.6 25-82 71.5-82 43.5.3 70.5 29 70.5 78.5zm-44.7-11v-2c-.3-20.7-6.7-35-24.8-35-15.3 0-24 9.4-26.2 37h51zm137-67.3c46.7 0 75 30 75 81.5 0 49-28.3 81.2-75 81.2-46.3 0-74.8-30-74.8-82 0-49 28.2-81 74.8-81zm0 33.4c-18.4 0-27.6 14.7-27.6 47.8 0 34 9.2 48 27.6 48 18.5 0 27.7-14.6 27.7-47.7 0-34-9.2-48-27.7-48zm156-33.4c-38.7 0-62.6 20.4-62.6 46.6 0 23.6 15 39.2 45.2 47.8 27 7.8 32 11 32 21.4 0 9.2-8.8 14.4-22 14.4-15 0-29-6-41-15L651 200c15 14 37.4 23 64 23 38 0 68-18.6 68-50.3 0-27.4-17-40-47.3-48.7-27.3-8-31.4-11.6-31.4-19.7 0-7 6-11.5 18.5-11.5 13 0 25.7 4.3 37.5 11.8l17-25.6c-14-11.6-34-18.8-56-18.8z" fill="currentColor" fill-rule="evenodd"/>
				</svg>
			</a>
		</h1>

		<p class="header-tagline">A cross-platform build system for creating iOS, macOS, Linux, and Windows programs.</p>
	</div>
</header>


	<main>
		<div class="container">
			<div class="row flex-md-row-reverse">
				<article class="col-md-9">
					<h1>Upgrading from legacy Theos</h1>
					<p>Theos in its current state is a continuation of the work done by Dustin Howett, with work from Ryan Petrich’s fork included (among others). As such, you can easily “upgrade” from one of these two most commonly used variants of Theos to this one.</p>

<p>If your copy of Theos was downloaded with Git, read on. If your copy of Theos was downloaded as a ZIP file from GitHub or from DHowett’s Subversion, you’ll want to make a backup of everything you’ve changed, delete the Theos directory, and then <a href="./Installation.html">install Theos from scratch</a>.</p>

<p>Simply change the remote repo and pull:</p>

<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gp">$</span><span class="w"> </span>git remote set-url origin https://github.com/theos/theos.git
<span class="gp">$</span><span class="w"> </span>git pull origin master
</code></pre></div></div>

<p>Then instruct Git to clone the submodules like so:</p>

<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gp">$</span><span class="w"> </span>git submodule update <span class="nt">--init</span> <span class="nt">--recursive</span>
</code></pre></div></div>

<p>Changing the Git remote URL isn’t strictly required, as DHowett/theos redirects to theos/theos. However, we recommend it to avoid confusion.</p>

<h2 id="things-to-be-aware-of">Things to be aware of</h2>
<p>Changes made since <a href="https://github.com/theos/theos/tree/legacy">legacy Theos</a> may catch you off guard. Here are some we think you should be aware of:</p>

<ul>
  <li><strong>Theos heavily relies on Git.</strong> Always install Theos <a href="./Installation.html">as directed</a>; do not download it as a ZIP.</li>
  <li><strong>The <code class="language-plaintext highlighter-rouge">theos</code> symlink is no longer created by NIC in new projects.</strong> The destination of this symlink can vary between computers, as Theos does not impose requirements on where it must be stored. The symlink is also often committed to source control (i.e., Git) unintentionally. As it was already highly recommended to set the <code class="language-plaintext highlighter-rouge">$THEOS</code> variable in your environment, we have opted to switch new makefiles to use <code class="language-plaintext highlighter-rouge">$THEOS</code> instead of the symlink. Changing this in your existing projects is recommended. Refer to <a href="./FAQ.html#wheres-the-theos-symlink">this FAQ entry</a>.</li>
  <li><strong>Configuration related to your environment, rather than the project, should be in <code class="language-plaintext highlighter-rouge">~/.theosrc</code>.</strong> If you set variables that are specific to your own setup, such as the location of Xcode/an SDK, device IP, etc., you should avoid placing it in your project makefile, as these types of things can vary between users. Move these to <code class="language-plaintext highlighter-rouge">~/.theosrc</code>, a makefile that is read and executed during an early stage of Theos’ <code class="language-plaintext highlighter-rouge">common.mk</code>.</li>
  <li><strong>Built packages have been moved to a directory called <code class="language-plaintext highlighter-rouge">packages</code>.</strong> The intent here is to reduce clutter in the root project directory and separate build output from the project source.</li>
  <li><strong>The <code class="language-plaintext highlighter-rouge">obj</code> directory has been moved to inside <code class="language-plaintext highlighter-rouge">.theos</code>.</strong> Again, this is for cleanliness. You may need to enable displaying of hidden files in your operating system/file manager to see this directory.</li>
  <li><strong>The linker flag required for tweaks to run in 32-bit processes on 64-bit devices running iOS 9 is not necessary.</strong> Theos already applies it for you.</li>
  <li><strong>Theos comes with some built-in headers and libraries for your convenience.</strong> These are maintained as Git submodules in the <code class="language-plaintext highlighter-rouge">vendor</code> directory. In particular, the libraries are in the plain-text format <code class="language-plaintext highlighter-rouge">.tbd</code> which is supported as of Xcode 7.0. If you have your own headers and libraries, place them in the <code class="language-plaintext highlighter-rouge">include</code> and <code class="language-plaintext highlighter-rouge">lib</code> directories in the root of Theos, not in <code class="language-plaintext highlighter-rouge">vendor</code>. You can override files in the vendor directories by using the same file path and name.</li>
  <li><strong>Theos no longer relies on <code class="language-plaintext highlighter-rouge">dpkg-deb</code>.</strong> After lzma compression with <code class="language-plaintext highlighter-rouge">dpkg-deb</code> was deprecated, <a href="https://github.com/theos/dm.pl">dm.pl</a> became Theos’ <a href="https://github.com/theos/theos/commit/bad135c47c1c3e0300fe823e64862f490830eee3">primary means of deb creation</a>, enabling the continued use of lzma compression. This was required because the current format dpkg-deb uses (xz) is not supported by Telesphoreo’s old dpkg build. Additionally, dm.pl eliminates Theos’ dependency on dpkg, enabling greater support for platforms that lack dpkg (e.g., Cygwin).</li>
  <li><strong>Theos defaults to building for ARMv7 and ARM64</strong> when linking against iOS 7.0 SDK or newer. If this needs to be changed in future, Theos will update the default accordingly. You should not set <code class="language-plaintext highlighter-rouge">$ARCHS</code> in your makefile unless you have a specific reason to.</li>
  <li><strong>Setting <code class="language-plaintext highlighter-rouge">$THEOS_DEVICE_PORT</code> is no longer required.</strong> If you use an <a href="http://mattryall.net/blog/2008/06/ssh-favourite-hosts">SSH host alias</a>, the port you specify in the SSH config file will be used. If the port isn’t set here or the hostname isn’t an alias, port 22 will be used.</li>
  <li><strong>The GCC compiler is no longer supported for Darwin targets.</strong> GCC was removed in Xcode 4.2 and use of it was discouraged for some time before that. On iOS, the very old <code class="language-plaintext highlighter-rouge">iphone-gcc</code> package has been superseded with a modern LLVM/Clang toolchain. If you use code that Clang does not like, you must port it to Clang or stick to legacy Theos.</li>
  <li><strong>The <a href="http://clang.llvm.org/docs/Modules.html#introduction">modules</a> feature of Clang is enabled</strong> if you use the iOS 8.3 SDK or newer. This solves <a href="https://clang.llvm.org/docs/Modules.html#problems-with-the-current-model">some limitations</a> of the dependency system compilers have traditionally used and improves performance (modules are cached in an optimised file format). That being said, there are <a href="https://clang.llvm.org/docs/Modules.html#problems-modules-do-not-solve">some limitations</a> that you may encounter.</li>
  <li><strong>Makedeps is disabled by default.</strong> As error output from Makedeps can be confusing, and the majority of projects do not use this feature, it has been changed to be off by default. To enable it, set <code class="language-plaintext highlighter-rouge">USE_DEPS = 1</code>.</li>
  <li><strong>Architecture slices are compiled separately and merged.</strong> This allows for architecture-specific configuration and fixes Makedeps for multi-architecture builds.</li>
</ul>

<p>If you come across something that should be listed here, edit the page and add it!</p>

<p>Aside from these changes, which shouldn’t affect the majority of projects, we expect projects to continue to build with the latest Theos without any changes required. If you find something odd, <a href="https://github.com/theos/theos/issues">let us know</a>!</p>

				</article>

				<aside class="col-md-3">
					<ul>
  
  <li>
    
      <a href="./index.html">Home</a>
    
    
  </li>
  
  <li>
    
      <a href="./Installation.html">Installation</a>
    
    
      <ul>
        
          <li>
            <a href="./Installation-iOS.html">
              iOS
              
            </a>
          </li>
        
          <li>
            <a href="./Installation-macOS.html">
              macOS
              
            </a>
          </li>
        
          <li>
            <a href="./Installation-Linux.html">
              Linux & Windows
              
            </a>
          </li>
        
          <li>
            <a href="./Upgrading-from-legacy-Theos.html">
              Upgrading from legacy Theos
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
  <li>
    
      <span>Usage</span>
    
    
      <ul>
        
          <li>
            <a href="./Concepts.html">
              Concepts
              
            </a>
          </li>
        
          <li>
            <a href="./Configuration.html">
              Configuration
              
            </a>
          </li>
        
          <li>
            <a href="./Commands.html">
              Commands
              
            </a>
          </li>
        
          <li>
            <a href="./Packaging.html">
              Packaging
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
  <li>
    
      <a href="./Features.html">Features</a>
    
    
      <ul>
        
          <li>
            <a href="./NIC.html">
              NIC
              
            </a>
          </li>
        
          <li>
            <a href="./NIC-Syntax.html">
              NIC Syntax
              
            </a>
          </li>
        
          <li>
            <a href="./dm.pl.html">
              dm.pl
              
            </a>
          </li>
        
          <li>
            <a href="./Swift.html">
              Swift
              
            </a>
          </li>
        
          <li>
            <a href="./Modules.html">
              Modules
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
  <li>
    
      <span>Tweak Development</span>
    
    
      <ul>
        
          <li>
            <a href="./Logos.html">
              Logos
              
            </a>
          </li>
        
          <li>
            <a href="./Logos-Syntax.html">
              Logos Syntax
              
            </a>
          </li>
        
          <li>
            <a href="./logify.pl.html">
              Logify
              
            </a>
          </li>
        
          <li>
            <a href="./Logos-File-Extensions.html">
              File Extensions
              
            </a>
          </li>
        
          <li>
            <a href="./Logos-Hook-Splitting.html">
              Hook Splitting
              
            </a>
          </li>
        
          <li>
            <a href="https://orion.theos.dev/" target="_blank" rel="noopener">
              Orion
              
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                  <path d="M1 11L11 1"/>
                  <path d="M2.5 1H11V9.5"/>
                </svg>
              
            </a>
          </li>
        
          <li>
            <a href="./Rootless.html">
              Rootless
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
  <li>
    
      <span>Technical</span>
    
    
      <ul>
        
          <li>
            <a href="./Structure.html">
              Structure
              
            </a>
          </li>
        
          <li>
            <a href="./Variables.html">
              Variables
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
  <li>
    
      <a href="./Help.html">Help</a>
    
    
      <ul>
        
          <li>
            <a href="./FAQ.html">
              FAQ
              
            </a>
          </li>
        
          <li>
            <a href="./Parallel-Building.html">
              Parallel Building
              
            </a>
          </li>
        
          <li>
            <a href="./arm64e-Deployment.html">
              arm64e Deployment
              
            </a>
          </li>
        
          <li>
            <a href="./License.html">
              License
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
  <li>
    
      <span>See also</span>
    
    
      <ul>
        
          <li>
            <a href="https://theapplewiki.com/" target="_blank" rel="noopener">
              The Apple Wiki
              
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                  <path d="M1 11L11 1"/>
                  <path d="M2.5 1H11V9.5"/>
                </svg>
              
            </a>
          </li>
        
          <li>
            <a href="https://www.reddit.com/r/jailbreakdevelopers" target="_blank" rel="noopener">
              /r/jailbreakdevelopers
              
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                  <path d="M1 11L11 1"/>
                  <path d="M2.5 1H11V9.5"/>
                </svg>
              
            </a>
          </li>
        
          <li>
            <a href="https://github.com/theiostream/theos-ref" target="_blank" rel="noopener">
              theos-ref (legacy docs)
              
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                  <path d="M1 11L11 1"/>
                  <path d="M2.5 1H11V9.5"/>
                </svg>
              
            </a>
          </li>
        
      </ul>
    
  </li>
  
</ul>

				</aside>
			</div>
		</div>
	</main>

	<footer role="navigation">
	<ul class="footer-sub-links">
		<li><a href="./">Docs</a></li>
		<li><a href="./Help.html">Get Help</a></li>
		<li><a href="https://github.com/theos" rel="me">GitHub</a></li>
		<li><a href="https://procursus.social/@theos" rel="me">@theos@procursus.social</a></li>
		<li><a href="https://twitter.com/theosdev" rel="me">@theosdev</a></li>
		<li><a href="/discord">Discord</a></li>
	</ul>

	<div class="footer-legal">
		Copyright &copy; Theos.
		<br>
		<a href="https://github.com/theos/theos.dev">Edit on GitHub</a>
	</div>
</footer>

</body>
</html>
